home *** CD-ROM | disk | FTP | other *** search
/ Apple Developer Connection Student Program / ADC Tools Sampler CD Disk 3 1999.iso / Metrowerks CodeWarrior / Java Support / Java_Source / IFC_112 / netscape / util / Codable.java < prev    next >
Encoding:
Text File  |  1999-05-28  |  10.7 KB  |  223 lines  |  [TEXT/CWIE]
  1. // Codable.java
  2. // By Ned Etcode
  3. // Copyright 1995, 1996, 1997 Netscape Communications Corp.  All rights reserved.
  4.  
  5. package netscape.util;
  6.  
  7. /** The Codable interface declares the methods that permit objects of public
  8.   * classes to be archived and restored. If you are writing an application
  9.   * that simply stores and retrieves objects of a codable class (that is,
  10.   * the class implements the <b>Codable</b> interface), you don't need to
  11.   * know the details of the <b>Codable</b> interface. Rather, you use the
  12.   * methods provided by the <b>Archiver</b> and <b>Unarchiver</b> classes to
  13.   * store and retrieve codable objects. <P>
  14.   * However, if you are providing a class and you want applications to be
  15.   * able to archive and restore objects of that class, you must implement
  16.   * the <b>Codable</b> interface in that class. The methods of the
  17.   * <b>Codable</b> interface, called by <b>Archiver</b> and
  18.   * <b>Unarchiver</b> objects, enable an object to describe its essential
  19.   * characteristics, and encode and decode the state of those
  20.   * characteristics. </P>
  21.   * <P>When an <b>Archiver</b> object calls the codable object's
  22.   * describeClassInfo() method, the codable object provides its class name
  23.   * and version and a set of key/type pairs. The key is a string defined by
  24.   * the codable object's class that labels a characteristic of object of
  25.   * that class. The type is a constant, defined by the <b>Codable</b>
  26.   * interface, that identifies a codable data type.</P>
  27.   * <P>When an <b>Archiver</b> object calls the codable object's encode()
  28.   * method, the codable object describes its essential state by providing
  29.   * a set of key/value pairs. The key identifies a characteristic previously
  30.   * defined through <b>describeClassInfo()</b>. The value is the current
  31.   * value of the characteristic. Encoding an object refers to reporting its
  32.   * current key/value pairs.</P>
  33.   * <P>When an object is to be restored from an archive, IFC calls the
  34.   * object's empty constructor and then calls its <b>decode()</b> method to
  35.   * initialize it with the values of the object's characteristics saved in the
  36.   * archive. <i><b>Note:</b> that classes that support the <b>Codable</b>
  37.   * interface must provide a public empty constructor in order for decoding to
  38.   * work properly.</i> </P>
  39.   * <P>The <b>View</b> class is codable. If you subclass <b>View</b>, you
  40.   * need to implement the <b>Codable</b> interface to save what is unique about
  41.   * your class. </P>
  42.   * <P>The following sample shows how a custom subclass of <b>View</b> might
  43.   * encode itself. </P>
  44.   *
  45.   * <pre>
  46.   * public class MyView extends View {
  47.   *
  48.   *         Codable someObject;
  49.   *
  50.   *         public MyView() {
  51.   *         }
  52.   *
  53.   *         public void describeClassInfo(ClassInfo info) {
  54.   *                         super.describeClassInfo(info);
  55.   *                         info.addClass("MyView", 1);
  56.   *                         info.addField("someObject", OBJECT_TYPE);
  57.   *         }
  58.   *
  59.   *         public void encode(Encoder encoder) throws CodingException {
  60.   *                         super.encode(encoder);
  61.   *                         encoder.encodeObject("someObject", someObject);
  62.   *         }
  63.   *
  64.   *         public void decode(Decoder decoder) throws CodingException {
  65.   *                         super.decode(decoder);
  66.   *                         someObject = decoder.decodeObject("someObject");
  67.   *         }
  68.   *
  69.   *         public void finishDecoding() throws CodingException {
  70.   *                         super.finishDecoding();
  71.   *         }
  72.   * }
  73.   * </pre>
  74.   * @see Encoder
  75.   * @see Decoder
  76.   * @see Archiver
  77.   * @see Unarchiver
  78.   * @see ClassInfo
  79.   */
  80. public interface Codable {
  81.     /** The codable data type constant specifying data of type boolean.
  82.       */
  83.     public static final byte BOOLEAN_TYPE       =  0;
  84.     /** The codable data type constant specifying an array of data of type boolean.
  85.       */
  86.     public static final byte BOOLEAN_ARRAY_TYPE =  1;
  87.     /** Primitive Codable type.
  88.       */
  89.     public static final byte CHAR_TYPE          =  2;
  90.     /** Primitive Codable type.
  91.       */
  92.     public static final byte CHAR_ARRAY_TYPE    =  3;
  93.     /** The codable data type constant specifying data of type byte.
  94.       */
  95.     public static final byte BYTE_TYPE          =  4;
  96.     /** The codable data type constant specifying an array of data of type byte.
  97.       */
  98.     public static final byte BYTE_ARRAY_TYPE    =  5;
  99.     /** The codable data type constant specifying data of type short.
  100.       */
  101.     public static final byte SHORT_TYPE         =  6;
  102.     /** The codable data type constant specifying an array of data of type short.
  103.       */
  104.     public static final byte SHORT_ARRAY_TYPE   =  7;
  105.     /** The codable data type constant specifying data of type int.
  106.       */
  107.     public static final byte INT_TYPE           =  8;
  108.     /** The codable data type constant specifying an array of data of type int.
  109.       */
  110.     public static final byte INT_ARRAY_TYPE     =  9;
  111.     /** The codable data type constant specifying data of type long.
  112.       */
  113.     public static final byte LONG_TYPE          = 10;
  114.     /** The codable data type constant specifying an array of data of type long.
  115.       */
  116.     public static final byte LONG_ARRAY_TYPE    = 11;
  117.     /** The codable data type constant specifying data of type float.
  118.       */
  119.     public static final byte FLOAT_TYPE         = 12;
  120.     /** The codable data type constant specifying an array of data of type float.
  121.       */
  122.     public static final byte FLOAT_ARRAY_TYPE   = 13;
  123.     /** The codable data type constant specifying data of type double.
  124.       */
  125.     public static final byte DOUBLE_TYPE        = 14;
  126.     /** The codable data type constant specifying an array of data of type double.
  127.       */
  128.     public static final byte DOUBLE_ARRAY_TYPE  = 15;
  129.     /** The codable data type constant specifying data of type string.
  130.       */
  131.     public static final byte STRING_TYPE        = 16;
  132.     /** The codable data type constant specifying an array of data of type string.
  133.       */
  134.     public static final byte STRING_ARRAY_TYPE  = 17;
  135.     /** The codable data type constant specifying object data.
  136.       */
  137.     public static final byte OBJECT_TYPE        = 18;
  138.     /** The codable data type constant specifying an array of objects.
  139.       */
  140.     public static final byte OBJECT_ARRAY_TYPE  = 19;
  141.  
  142.  
  143.     /** Defines the key/type pairs that describe the essential characteristics
  144.       * of a class. Typically, this method is called by an IFC <b>Archiver</b>
  145.       * object, not an application. <P>Each class that can be archived has a
  146.       * schema that defines the critical information to be saved for a given
  147.       * instance of that class. This method provides the field names and
  148.       * <b>Codable</b> data types that define the information to be archived for
  149.       * object of a given classs, along with the class name and class version.
  150.       * The field names frequently correspond to the instance variables in the
  151.       * class.</P>
  152.       * <P>If you are providing a new class that you want to be archivable, you
  153.       * implement <b>describeClassInfo()</b> to describe the key characteristics
  154.       * of your class. If your class is a subclass of a <b>Codable</b> class,
  155.       * first call super.describeClassInfo() to allow the superclass to add its
  156.       * class name, class version, and key/type pairs. Then call info.addClass()
  157.       * and info.addField() to add the key/type pairs that describe your class.
  158.       * </P>
  159.       * <P>Note that because subclasses of your class can call this method, it
  160.       * might be invoked multiple times. As a result, <b>describeClassInfo()</b>
  161.       * should not contain any code that should not be executed more than once.</P>
  162.       * <P>See the sample code in the class description.</P>
  163.       * @param info  A ClassInfo object that describes the schema to encode
  164.       * the class. The called object populates the instance with the information
  165.       * for its class.
  166.       * @see ClassInfo
  167.       * @see Archiver
  168.       */
  169.     public void describeClassInfo(ClassInfo info);
  170.  
  171.     /** Encodes the essential state of an object. This method is called by an
  172.       * <b>Archiver</b> object to obtain the key/value pair information that
  173.       * defines the called object's current state.
  174.       * <P>An object of a class that implements this method calls the
  175.       * appropriate Encoder methods to provide key/value pair information for
  176.       * the characteristics defined by its <b>describeClassInfo()</b> method.
  177.       * </P><P>The order in which an object encodes its key/value pairs is not
  178.       * important. However, it is more efficient to encode them in the same
  179.       * order that the keys are added in <b>describeClassInfo()</b>. </P>
  180.       * <P>See the class description for information about key/value pairs.
  181.       * @param encoder  An Encoder object that stores state information for an
  182.       * object to be archived. The called object populates the instance with
  183.       * information about its state.
  184.       * @exception CodingException  Occurs when the object cannot be encoded
  185.       * completely.
  186.       * @see Encoder
  187.       * @see Archiver
  188.       */
  189.     public void encode(Encoder encoder) throws CodingException;
  190.  
  191.     /** Restores an archived object's essential state. Typically, an
  192.       * <b>Archiver</b> object calls this method immediately after calling the
  193.       * archived object's empty constructor. The new object then restores
  194.       * the saved state by calling the appropriate Decoder methods.
  195.       * <P>When implementing this method, you can restore your object's key/value
  196.       * pairs in any order. However, it is most efficient to decode them in
  197.       * the same order that you add the keys in the <b>describeClassInfo()</b>
  198.       * method. </P>
  199.       * @param decoder  A Decoder object containing the saved state
  200.       * information for the object to be restored.
  201.       * @exception CodingException  Occurs when the object cannot be decoded
  202.       * completely.
  203.       * @see Decoder
  204.       * @see Unarchiver
  205.       */
  206.     public void decode(Decoder decoder) throws CodingException;
  207.  
  208.     /** Gives a restored object an opportunity to communicate with its related
  209.       * objects after all have been decoded. When an object containing a reference
  210.       * to another encoded object is restored from an archive, the referenced
  211.       * object may not be fully initialized. This method provides an opportunity
  212.       * to complete the initialization. More specifically, objects retrieved from
  213.       * <b>decodeObject()</b> might not have been fully initialized, so
  214.       * finishDecoding() gives newly created instances an opportunity to talk to
  215.       * other objects just after <b>decode()</b> hasbeen called on all of them.
  216.       * @exception CodingException  Occurs when the object cannot be encoded
  217.       * completely.
  218.       * @see Decoder
  219.       * @see Unarchiver
  220.       */
  221.     public void finishDecoding() throws CodingException;
  222. }
  223.